Repository navigation
v3.0.0: typed, safe rewrite with 2.x compatibility facade - #14
Merged
Merged
Conversation
Goal (v3 rewrite): turn PythonMetaTrader5 into a typed, tested library whose trading calls never block forever, with a 2.x compatibility facade. - Stop tracking the generated egg-info directory and add a .gitignore. - Declare the real license (CC-BY-NC-4.0, SPDX) instead of the contradictory MIT classifier, and ship a LICENSE file. - Mark the MetaTrader5 dependency win32-only: the official package has Windows wheels only, so an unconditional dependency breaks Linux CI and type checking. - Raise the floor to Python 3.10 (match statements, PEP 604 unions); 3.6-3.9 are end-of-life. - Configure pytest, coverage, ruff and mypy --strict.
Replaces the 2.x single-file Broker (its behaviour returns as a compatibility facade in a later commit). The domain has no I/O and never imports MetaTrader5. - Result (Ok/Err) for every expected failure at boundaries. - SymbolSpec: price normalisation on the tick grid, not only to `digits` (index CFDs with tick 0.25 were rejected by 2.x), volume min/max/step validation, filling-mode choice from the symbol's flags. - Stop: SL/TP as a price or as a distance in points (2.x semantics kept). - Retcode classification. Retry only codes where the server provably did not execute; TIMEOUT/CONNECTION are not retried because the order may already be live and a retry would open a duplicate position. - Comments over 31 characters are rejected instead of silently truncated.
Ports exist only for the two process boundaries: the MT5 terminal and time. - open_position: SL/TP as prices (floats) or Stop.points distances, requotes retried with a fresh quote at most RetryPolicy.attempts times. 2.x looped forever on any unknown retcode (e.g. NO_MONEY), sending an order every 0.5 s. - place_limit_order: RETURN filling, success on PLACED (10008). - close_positions: closes each position on its own symbol. 2.x priced every close with the `symbol` argument, so close-by-ticket with symbol=None crashed. - Batch operations return BatchFailure listing what succeeded and what failed, instead of a boolean that hid partial closes. - magic filters for close/cancel/queries so a bot never touches manual trades.
- MetaTrader5Terminal is the only module that knows MT5 request dicts and numeric order types. It imports the package lazily, so the library (and its unit tests) import on Linux where MetaTrader5 has no wheels. - Hidden symbols are selected into Market Watch automatically; a quote with a zero side is refused instead of trading at price 0. - None from positions_get/orders_get is split into "empty" vs "failed" via last_error(); 2.x treated a broken IPC link as "no positions". - connect() is the composition root and logs login@server only; 2.x logged the whole account_info (owner name, balance). - Broker keeps 2.x names, arguments and return shapes and emits a DeprecationWarning. It no longer loops forever and no longer presses Ctrl+E: that hotkey toggles (not enables) Algo Trading and is typed into whichever window has focus. - Logging uses stdlib `logging` without a NullHandler: with a NullHandler an unconfigured script would silently swallow every ERROR record, whereas stdlib's last-resort handler still prints them to stderr. - .gitattributes normalises line endings to LF.
- Unit tests, ruff and mypy --strict on Python 3.10-3.14 (Linux). - A Windows job installs the real MetaTrader5 wheel and builds the adapter against it, so a renamed constant fails CI instead of a live order. - Semgrep: ERROR (high/critical) findings block the merge; WARNING (medium) findings are listed for the PR description. - scripts/check_file_length.py enforces the 300-line limit on tracked files. - Package build + twine check --strict. - Actions pinned to commit SHAs so a moved tag cannot inject code. - Integration tests run only with MT5_* credentials and refuse to trade on a non-demo account; they use a dedicated magic number for cleanup.
…d ADRs ADRs record each decision as 'A over B because B silently breaks C': ports per process boundary, Result at boundaries, bounded retries with no retry on unknown outcome, no GUI automation, stdlib logging without a NullHandler, the 2.x facade, filling mode and tick-grid pricing.
All found by /code-review high on this branch, each reproduced by a failing
test first (tests/unit/test_safety_edges.py).
- An empty symbol is rejected: MT5 treats a falsy filter as all symbols, so
close_positions("") would have closed the whole account. The adapter now
forwards "" as a filter instead of dropping it.
- Broker.Close(None) without a ticket closes nothing, as 2.x did.
- order_send returning None is OUTCOME_UNKNOWN unless last_error proves the
request never left the process; a plain TERMINAL_ERROR invited a re-send.
- symbol_select failure is an error; a missing first quote is retried since
nothing was sent yet.
- DONE_PARTIAL on a close is a PARTIAL_FILL error.
- Pending orders use the symbol filling mode: a fixed RETURN is refused by
market-execution brokers, where the 2.x IOC was accepted.
- connect() maps any unusable login to INVALID_ARGUMENT and shuts the
terminal down after a failed login.
- close-all reads each symbol spec once; closes use Tick.exit_price.
- SymbolSpec.stops_level removed: unused, and a local check would be wrong
for brokers with floating stop levels (stops_level 0).
The Windows CI job builds the adapter against the real MetaTrader5 wheel; with constants resolved lazily in _payload/_position a renamed TRADE_ACTION_* or ORDER_TIME_GTC would only fail on the first live order. Also states in the README and docstring that close_positions() and cancel_pending_orders() without arguments act on the whole account.
Each finding reproduced by a failing test first (test_safety_edges.py). - Pending orders on exchange-execution symbols use RETURN, the only mode that lets a limit rest in the book; elsewhere the symbol market rule stays. - A close counts as done only on DONE; PLACED is OUTCOME_UNKNOWN and DONE_PARTIAL is PARTIAL_FILL. - The adapter shuts the half-open session down after a failed login, so the Broker.login(ToEffect=True) loop can recover; connect() no longer does it. - Broker.CancelOrders(None) cancels nothing, as 2.x did. - Logins that int() would silently coerce (True, 12345678.9, negatives) are rejected instead of logging into another account. - RES_E_* codes come from the MetaTrader5 module and last_error() is read once per failure. - Unit tests patch MetaTrader5 with a fake (autouse): a new test reached the real initialize() and hung until timeout. - README: one connection per process (the package is a global singleton). Field removal check required by project rules for SymbolSpec.stops_level (removed in a5a03d4), grep over the whole repo: $ grep -rn stops_level --include=*.py --include=*.md --include=*.toml . src/PythonMetaTrader5/domain/retcodes.py:39 (10016 message) -> reworded tests/unit/fake_mt5.py:99 (fake trade_stops_level) -> removed after this commit: no references left. No DB, FKs, triggers or views exist.
…sions
Third review round; each finding reproduced by a failing test first
(tests/unit/test_confirmation.py).
- execute() confirms every market deal (entry and close) only on DONE.
DONE_PARTIAL is PARTIAL_FILL and PLACED is OUTCOME_UNKNOWN, both with the
receipt and never re-sent. The close-only special case is gone. Returning
Ok for a partial entry let a bot believe it held 1 lot while holding 0.3.
- parse_login() is shared by connect() and Broker: ASCII digits or an
int-like value via operator.index, so numpy ints still work while True,
floats and non-ASCII digits (int("١") == 1) are rejected.
- A failed re-login no longer shuts down a session this adapter opened; MT5
keeps one session per process, so that killed a working connection.
- SymbolSpec.exchange_execution is required: a default would quietly treat an
exchange symbol as market execution. Adapter mapping now has a test.
- RES_S_OK read from the module; last_error() formatted in one place.
- README, MIGRATION, CHANGELOG and ADR 0003/0007 updated to the new rules.
Fourth review round. The previous commit kept a "live" session after a failed re-login using a per-adapter flag. That was wrong: MT5 has one session per process and connect() builds a new adapter each time, so the flag protected nothing, and it stopped login(ToEffect=True) from ever recovering because the half-open session was never released. Reproduced by failing tests first. - The adapter always calls shutdown() after a failed initialize(); Broker marks itself disconnected so nothing trades on a released session. - Credentials validates the login itself, so no construction path can hand MT5 True or a float. - PARTIAL_FILL names the requested size and warns that with RETURN filling the remainder may still be working. - A detached comment about RES_S_OK moved next to the code it explains.
Semgrep MEDIUM (github-actions-mutable-action-tag) x2 in python-publish.yml. Pinned to the SHAs the v4/v5 tags point at today, so publishing behaves exactly as before while a re-pointed tag can no longer inject code into the job that holds the PyPI token.
… MT5 calls
Found by three independent reviews after the fourth /code-review round.
- sl=0 / tp=0 (or a price that snaps to 0.0, or a points distance that
goes below zero) is INVALID_STOPS. MT5 reads 0.0 as "no stop", so a
webhook with a missing SL field opened an unprotected position and
reported Ok.
- A ticket that is not a positive integer (0, -5, True, 1.0, "7") is
INVALID_ARGUMENT before positions_get is called; positions_get(ticket=0)
may mean "no filter", which would close the whole account.
- Volume and prices must be positive finite numbers (numbers.Real, not
bool): NaN/inf raised ValueError/OverflowError instead of returning Err,
and volume=True traded one lot. volume_step <= 0 is an Err, not a
ZeroDivisionError.
- The adapter applies symbol and ticket together; MT5 drops `symbol` once
`ticket` is given, so positions("EURUSD", ticket=t) could return a
position on another symbol.
- Every adapter call holds a module-level RLock, so an MT5 call and the
last_error() read that explains it cannot interleave with another
thread. A per-adapter lock instead of a module lock: rejected, because
connect() builds a new adapter per call and two Traders share the one
process-global session, so per-adapter locks protect nothing.
Splits (300-line limit, each one concern):
- domain/inputs.py: input rules with no I/O; plain functions, not a port.
- application/entries.py: Entry and validate_entry, the one place raw entry
input becomes a request; Entry.request is an entity method instead of a
Trader helper because it needs only the entry's own data.
- adapters/mt5_mapping.py: pure MT5-object -> domain mapping.
Removed/renamed private helpers; grep over src tests docs scripts *.md
.github for _reject_empty|_as_stop|_order_type_table|_validate_entry|
_entry_request|\._position\(|_Entry\b: no matches outside stale __pycache__.
RED: 36 of 40 new cases failed (4 of the volume cases already passed: 0, -0.1 and -inf are caught by the range check, and None by float() raising), the resolve-to-zero cases failed with
the guard disabled, and the lock test failed before the lock existed.
…eric strings The 2.x Broker returned raw MetaTrader5 objects. MIGRATION promised "same fields", but scripts using the missing ones broke, and no test noticed. - GetPositions(): LegacyPosition now has every TradePosition field in MT5's order (swap, identifier, reason, time_msc, time_update, time_update_msc, external_id were missing; p[1] was symbol instead of time). as_dict=True keeps exactly the 12 keys 2.x built. - Entries return LegacyReceipt, shaped like OrderSendResult: it gains retcode_external, indexing and _asdict(). `request` is always None because 3.x does not keep the echoed request. - Volume, price, sl, tp and stoplimit given as strings are converted with float(), as 2.x did; garbage raises ValueError as in 2.x. Only strings are converted: float(True) would trade a stray bool as one lot. This also fixes a regression from 55be3e2, where Buy("EURUSD", "0.1") was refused. - GetPositions(symbol, ticket=) selects by ticket alone, as in 2.x. Position gains the extra fields in the domain rather than the legacy layer keeping raw MT5 objects, which would bring MT5 types back into the facade the port exists to isolate. TradeReceipt gains retcode_external. Test helpers that built Position by hand now share fakes.make_position. Split: legacy/arguments.py takes the pure 2.x argument rules out of broker.py (300-line limit). Moved private names _legacy_stop and _no_ticket: grep over src tests docs scripts *.md .github finds no remaining use. RED: all 7 tests in test_legacy_compat.py failed before the change.
…tries The docs/tests review found test gaps that hid or could hide real bugs: - tests/contract checks FakeMT5 constants, the fake result rows and the legacy NamedTuples against the installed MetaTrader5 package (values, field names and order). They sit outside tests/unit because the autouse fixture there swaps the module for FakeMT5. The Windows CI job ran the same faked unit tests as Ubuntu; it now runs these against the real wheel. Shown to fail by setting ORDER_FILLING_RETURN to 3 in the fake. - login(ToEffect=True) never looped in any test (FakeTerminal could not fail N times, then succeed); it now has connect_failures and a test. - Broker without an injected terminal (the production path) is covered. - Weak asserts tightened: - The password check used the one-letter password "p". - A positions() magic filter was checked on an empty list. - CancelOrders() "is None" was always true. - A test name claimed a recovery the fake cannot model. - The ci.yml comment on the Windows job now says what it proves.
…R 0008-0009 Docs fixes found by the independent reviews: - CHANGELOG said a failed re-login keeps a working session. bc237d4 reversed that, and the entry was never updated. - MIGRATION said invalid input returns "the receipt". It returns None, because nothing was sent. - MIGRATION said GetPositions has "the same fields". It now does, and the entry says so precisely. - The MIGRATION example `[p.to_dict() for p in trader.positions().value]` raised on Err. It now matches on Ok/Err and notes `side` vs `type`. - README said BatchFailure.succeeded shows "exactly which tickets closed". The receipts carry deal/order IDs, not position tickets. - README and ADR 0003 said "every call returns". Broker.login(ToEffect=True) loops by design, and batches take the time limit per position. - architecture.md said legacy works "through Trader and ports". It builds the default adapters itself. MIGRATION gains the behaviour changes that were missing: - failed logins disable the Broker, and one shared session per process; - invalid input is refused before sending; - sl=0 and unknown sl_type (2.x opened with no SL and no TP); - volume=True; - offset stops with an explicit price, including the market-execution case; - Close() no longer loops, so a Close-then-Buy reversal must check the result; - ticket=0; - receipt and position shapes; - the time/logger/pyautogui star exports; - DeprecationWarning under -W error; - limit-order filling. ADR 0008 records why such inputs are refused. ADR 0009 records why the terminal lock is per process, not per adapter.
…ecimal - Legacy BuyLimit/SellLimit compared the raw stoplimit with the quote before any check. SellLimit(s, v, 0) "crossed" and was sent as a market SELL, and inf or True did the same. The level is now checked first. - Stop.at_price()/points() ran float() on their argument, so True became 1.0 before stop_input could refuse it. Broker(..., sl=True) opened with sl=1.0. The factories now store the value unconverted, stop_input checks it and rebuilds the Stop from the checked float, and the sign of a points distance is dropped in Stop._resolve. - Decimal volumes and prices were refused because Decimal is not a numbers.Real. They worked before via float(), so this was a regression from 55be3e2. Decimal is now accepted explicitly. - A bad price was checked after the symbol lookup. That cost a terminal round trip and could add the symbol to Market Watch. It is now checked first. - as_dict builds the 2.x dict straight from Position. _V2_DICT_KEYS is removed; grep over src tests docs finds no other use. - A test-fake comment now states the decision, not the action. Not changed: number() conversion stays at the two legacy entry points (OpenPosition, _limit). Every legacy entry method goes through one of them, so a separate normaliser would be a third place to keep in sync. RED: 7 of the 8 new cases failed before the change. The legacy limit at NaN already returned None, because comparisons with NaN are false.
… validate_entry Second /code-review high round, on 23f78ff, which went the wrong way: - Stop stored raw values and left the checks to stop_input. That made it an anemic value object (the project rules forbid that), and two stops with the same meaning stopped being equal: Stop.points(-1000) != Stop.points(1000). Stop.points(Decimal(...)).stop_loss() also raised TypeError. Stop now enforces positive-finite-float in __post_init__ and drops a distance's sign there, so the sign rule lives in one place instead of two. It raises ValueError, because a zero Stop cannot exist. Plain floats passed as sl/tp still come back as Err(INVALID_STOPS) from stop_input, without raising. - Decimal("sNaN") raised ValueError / InvalidOperation out of the Result boundary. domain/amounts.positive_float is the single rule, used by both Stop and positive_number, and checks Decimal NaN before float(). It is a plain function because it is pure: no port, no use case. - "Check the price before the symbol lookup" was a convention each caller had to remember. The price is now validated inside validate_entry, after side/comment/stops, so a bad side is still the first error reported. Entry carries the price on the tick grid. - as_dict is again a projection of as_object() (_V2_DICT_KEYS restored). The previous round's hand-written dict was a second mapping that could drift. Correctness wins over one allocation per row. - Tests: the bool-stop test no longer runs its Trader loop once per sl_type for nothing. The bad-price test asserts INVALID_PRICE. Error precedence is pinned. Not changed: - The legacy crossing test still compares the raw level with the quote, as 2.x did (BuyLimit: `info.ask <= float(stoplimit)`). - The legacy level check is repeated inside place_limit_order. The first check must run before the crossing test, and the second protects the 3.x API. RED: against 23f78ff's src, 20 of the new or changed cases failed (sNaN raising, Stop equality and Decimal, the Entry price field).
…r rule Third /code-review high round, on 2359877: - An explicit price that snaps to 0.0 on the tick grid (price=1e-6 on a 5-digit symbol) was sent. A deal at price 0 fills at the market, which silently drops the caller's price. validate_entry now refuses it with INVALID_PRICE, the same guard the stops already had. - positive_float raised OverflowError on 10**400. It now returns None, so every Result path stays non-raising, including the legacy offset stop. - Stop.parse(value, kind) -> Result is the non-raising way to build a stop from a value that may be bad at runtime, e.g. an ATR that is NaN during warm-up. stop_input and legacy_stop use it, so legacy no longer catches ValueError for control flow. The constructors still raise: a Stop of 0 cannot exist, and that is the one case where the project rules allow a domain exception. Rejected alternative: making the constructors return a Result, which would turn `sl=Stop.points(1000)` into an unwrap at every call site. - Stop(1000, "points") (a str instead of a StopKind) was silently a PRICE stop. It now raises TypeError. - The retry policy is derived from e.price, the same source build() uses. - README, ADR 0008 and CHANGELOG describe the raising and the non-raising path. StopKind is exported for Stop.parse. Not changed: - Entry.request(quote=None) stays. A priced entry ignores the quote by design, and a missing price is an explicit NO_PRICE Err, covered by a test. - as_dict stays a projection of as_object. The comment now names sl/tp as the one intended difference. RED: the 4 new tests failed before the change.
Fourth /code-review high round, on 591f1cb: - price=1e305, a limit at 1e305 and sl/tp=1e305 raised OverflowError. They passed the number rule (finite), then 1e305 / 1e-5 overflowed to inf in normalize_price and round(inf) raised. SymbolSpec.price_on_grid is now the single place every sent level (entry price, sl, tp) goes on the grid. It returns Err on overflow, on a level that snaps to 0 or below, and on a symbol with neither tick size nor point. This replaces the two ad-hoc "normalize, then check <= 0" copies, which had already diverged: neither one guarded the overflow. Stop.stop_loss/take_profit return a Result accordingly. - Stop.parse(0, "points") raised AttributeError and Stop.parse(5, "points") raised TypeError. The kind check now runs first, inside the shared _checked, so a wrong kind is always a TypeError. - positive_float catches only OverflowError, the one named case. Catching ValueError would have hidden bugs in a caller's own number type, with a misleading message and no traceback. - README, ADR 0008 and CHANGELOG now say exactly what the Stop constructors raise on, and how large finite floats are handled. Not changed: Stop.parse validates once in _checked and again in __post_init__. Both calls go through the same function, so they cannot diverge, and the alternative of catching ValueError is the exception-driven control flow the previous round removed. RED: the overflow and parse-kind tests failed before the change. The test_stops expectations moved to Ok(...) with the new return type.
…before quotes Fifth /code-review high round, on 048ab75: - With point=inf (and tick_size=0), price_on_grid returned Ok(nan) and an order priced NaN was sent. With point=0, Stop.points(1000) resolved to the entry price. SymbolSpec now has an invariant: point, volume_step and volume_min must be positive and finite, tick_size must be 0 or positive and finite, volume_max must be >= volume_min, and digits >= 0. __post_init__ raises, because such a spec cannot exist, and the adapter goes through SymbolSpec.check, which turns broken data into Err(TERMINAL_ERROR). This removes the scattered step guards in validate_volume and price_on_grid. They are unreachable now, and they had already missed the inf case. The step choice lives once, in _step. - Absolute sl/tp are checked on the grid in validate_entry. A stop that can never be valid no longer waits through the NO_PRICE retries of a symbol without quotes before it is reported. - positive_float catches ArithmeticError (overflow, and numpy FloatingPointError under seterr), which covers numbers out of range. It still lets ValueError/TypeError through: those are bugs in the caller's own type. - The price_on_grid docstring and ADR 0008 no longer claim that quote prices pass through it. A stops.py comment now states the decision. Not changed: - Stop.parse raises TypeError on a kind that is not a StopKind. A config string has to go through StopKind(...) first, which raises ValueError by itself. - Stop.stop_loss/take_profit returning a Result needs no migration note: Stop is new in 3.0, which is unreleased. RED: all 19 cases in the new test_symbol_data.py failed before the change. The two tests that built impossible specs (volume_step=0, point=0) were replaced by adapter-level tests, because such specs can no longer be built.
Sixth /code-review high round found a regression in a0f2aba, my own commit. Its constructor invariant on SymbolSpec made the adapter refuse the whole symbol, so close_positions() could no longer flatten a position on a symbol with odd data (volume_step 0, point 0), although closing needs only filling_flags. That is the most safety-critical path, so the invariant is removed and each field is checked where it is used: - price_on_grid refuses a step (tick size, else point) that is not positive and finite. - SymbolSpec.points_to_price refuses a point that is not positive and finite, for points stops only. A symbol with a valid tick size and point 0 can still trade absolute prices. - validate_volume refuses unusable min/max/step as INVALID_VOLUME. That is the error kind callers saw before a0f2aba, not TERMINAL_ERROR. - The adapter refuses NaN and infinite quotes as NO_PRICE. `nan <= 0` is False, so a NaN ask was sent as the order price. - A bad price is again reported before a bad absolute stop. SymbolSpec.check and _problem are removed. A grep over src tests docs *.md finds no remaining use. ADR 0008 records why the whole-spec invariant was rejected. Not changed: absolute stops are snapped once in validate_entry (as a check) and again in Entry.request. That is the same pure function with the same result, and keeping one resolution path avoids a second source of truth for the sent level. RED: on a0f2aba, 24 of the 27 cases in test_symbol_data.py failed, including all 9 close cases. The FloatingPointError case already passed there and pins the ArithmeticError catch.
…a close Seventh /code-review high round, on 098ac0a: - A NaN or negative tick size silently fell back to `point`, and negative digits rounded to tens (5785.25 -> 5790.0). Both have been checked since a0f2aba removed the constructor invariant. - A market order without price or stops on a symbol with no usable step was still sent, because it never reaches price_on_grid. Every entry now calls SymbolSpec.check_tradable() first, which checks tick size, step, digits and volume limits. Closing never calls it. - Broken data was reported as INVALID_PRICE / INVALID_STOPS / INVALID_VOLUME, which blames the caller, so a bot would drop signals instead of escalating. It is now TERMINAL_ERROR with "broken symbol data" in the message. - normalize_price is folded into price_on_grid. As a public method it raised ZeroDivisionError or returned NaN on broken data. A grep over src tests docs README.md MIGRATION.md CHANGELOG.md finds no remaining use. - _usable drops runtime type checks the float-typed fields never needed. - An adapter-level test pins that broken symbol_info is passed on, not refused, so the a0f2aba close regression cannot come back through the adapter. CHANGELOG and ADR 0008 now describe what is actually refused. RED: on 098ac0a, 16 of the 34 cases in test_symbol_data.py failed (the new pricing cases, the market order without stops, and the error kinds).
…bol lookup Eighth /code-review high round, on a11a618. Only findings that send an unasked order, block a close, raise out of a Result boundary, or regress this branch are fixed here. The rest are listed in the PR as debt. - Broken symbol data came back as TERMINAL_ERROR, which ADR 0003 defines as "never sent, safe to resend". A bot following that rule would resend forever, because broken data does not clear. It now has its own kind, BROKEN_SYMBOL_DATA (escalate, don't retry). The README error table says so. - check_tradable ran after validate_volume, so broken data plus an out-of-range volume came back as the caller's INVALID_VOLUME. It now runs right after the symbol lookup (_tradable_spec), the one place every entry passes through. - _usable lost its type check in a11a618, so a hand-built spec with point=None raised TypeError out of check_tradable. The check is restored. RED: against a11a618's src, 18 of the 54 cases in test_symbol_data.py and test_symbol.py failed (the new kind, the precedence and the None point).
The owner asked to keep the MT5 functions in the package. The 2.x README
itself called `symbol_info("EURUSD")` after `from PythonMetaTrader5
import *`, so scripts written from it would hit NameError after a plain
`pip install -U`.
- legacy/mt5_namespace.py loads MetaTrader5 when it is installed and lists
its public names. __init__ adds them as package attributes and to
__all__. Our names win a collision: today only `Tick`, where MT5 has its
own tick struct. Without the package (Linux, macOS, CI) nothing is
added and the import still works.
- time, loguru's logger and pyautogui, which 2.x also leaked, are not
restored. Two are no longer dependencies, and a leaked stdlib module is
not an API.
- ADR 0010 supersedes the "drop the star re-export" part of ADR 0006 and
records the remaining cost: new MT5 names enter our namespace, and
MetaTrader5 is now imported eagerly. Importing it does not attach to a
terminal; only initialize() does.
- MIGRATION, CHANGELOG and README now describe the star import as it is.
RED: the unit tests failed on the missing module, and the contract star
import test failed with KeyError 'symbol_info'.
…on lock /code-review high on f3f835c found that the first draft was too shallow: - A broken MT5 install (DLL load failure, missing numpy) was hidden. Any ImportError meant "re-export nothing", and the user later got a NameError on symbol_info, far from the cause. Now only "MetaTrader5 is not installed" means no names. Any other import failure raises where an MT5 name is used, and the adapter reports it as "installed but cannot be imported" instead of "not installed". - The eager import made every `import PythonMetaTrader5`, even of domain types only, pay for MT5 and numpy (65 of 87 ms) and fail with them. The package now has a PEP 562 __getattr__: MT5 names resolve on first use, and a star import gets __all__ through the same hook. Our own names stay plain attributes and win (Tick). They are re-exported with `X as X` because __all__ is computed. - Re-exported functions bypassed the adapter's lock, so a direct last_error() could interleave with the adapter's order_send and make a lost order look "never sent". They are now wrapped to hold the same lock. adapters/mt5_session.py holds that lock and the one MetaTrader5 import site, shared by the adapter and the re-export, so the two can no longer diverge. - The wiring is unit-tested with the fake module: the star import, the lock, missing vs broken installs, dir(), no eager import, and that time/logger/pyautogui stay absent. The contract test checks the real package. - ADR 0010 records the lazy design and the typing cost: __getattr__ returns Any, so typos on the package root no longer fail type checks. ADR 0006's title marks the superseded part. The CHANGELOG moves the namespace from Removed to Changed. ADR 0009, architecture.md, MIGRATION and README mention the lock. Removed names (mt5_namespace.load, mt5_terminal._SESSION, _reexported): grep over src tests docs *.md finds no remaining use. RED: the new unit tests failed on the missing mt5_session module.
…ays why /code-review high on 05e3c35. Fixed: the findings that raise out of a Result boundary or regress this branch. - On a broken install, `from PythonMetaTrader5 import *` raised ImportError, even for scripts that only use connect(). hasattr(), getattr(.., default) and dir() raised as well, which breaks IDEs and pydoc. Now the star import keeps our names and emits a RuntimeWarning with the cause. An MT5 name raises AttributeError chained to the ImportError, so hasattr is False and the cause is kept. connect() returns Err(CONNECTION_FAILED). - An AttributeError or ValueError raised while MetaTrader5 imported (numpy ABI mismatch) escaped. The AttributeError read as "no __all__" and silently emptied the star import; others escaped connect() as raw exceptions. import_metatrader5 now turns every failure except "not installed" into ImportError with the cause, and the adapter already maps ImportError to Err. - Dead `taken` parameter dropped: a module __getattr__ only runs on misses. The collision filter for __all__ stays in __init__, where it takes effect. The `_serialized` alias and its comment are gone; methods use `@serialized`. - MIGRATION, README and ADR 0010 no longer claim that re-exported calls "cannot interleave". The lock covers one call, not a script's own order_send + last_error pair. - Tests patch mt5_session's importlib reference instead of the stdlib module, and cover ImportError, ModuleNotFoundError of a dependency, AttributeError and ValueError. Debt (ADR 0010): resolved names and the "not installed" outcome are not cached, so each access re-resolves. This affects performance and identity, not correctness. RED: 4 cases in test_mt5_namespace.py failed before the change.
…aveat Follow-up to the /code-review high findings on d046e6a. These are small, mechanical fixes and get no separate review round. The PR says so. - connect() on a broken install said "installed but cannot be imported" twice. load() now passes import_metatrader5's message through, and the test pins the exact text. - The RuntimeWarning used stacklevel 3 and so pointed at the library's __getattr__. It now uses 4 and names the user's import line. - import_metatrader5 has one except clause and one raise instead of two identical ones. - CHANGELOG gets the per-call lock caveat that README, MIGRATION and ADR 0010 already carry. - ADR 0010 lists the remaining debt: no caching of the import outcome, and on a broken install hasattr/getattr(..., None) do not warn while star import and dir() do.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Goal
Turn PythonMetaTrader5 into a typed, tested library whose trading calls never block forever, never retry blindly and never fail silently, while existing 2.x scripts keep running through a deprecated
Brokerfacade.What changed
Terminal,Clock).Result(Ok/Err) is used at every boundary. Seedocs/architecture.mdanddocs/adr/0001–0010.from PythonMetaTrader5 import *still brings in theMetaTrader5namespace (symbol_info,ORDER_TYPE_BUY, ...), as the 2.x README relied on.Tick).connect()returnErr.hasattr/getattr(.., None)give False without a warning.connect()→Traderwithopen_position,place_limit_order,close_positions,cancel_pending_orders,positionsandpending_orders. It adds magic numbers,Stop.points(),Stop.parse()and typedErrorKinds.Brokerkeeps the same names and arguments. It returnsLegacyPosition/LegacyReceiptnamed tuples with MT5's field names and field order, and emits aDeprecationWarning.sl=0("no stop"),ticket=0,volume=True, NaN or infinite numbers, prices that snap to 0, an empty symbol.BROKEN_SYMBOL_DATA; closes still work on such symbols.MetaTrader5is installed only on Windows.pyautoguiandloguru.py.typed.tests/contractagainst the realMetaTrader5wheel (constant values, result field names);twine check.Every behaviour change for users is listed in MIGRATION.md.
Review history (honest account)
After four
/code-review highrounds, three independent reviews (trading correctness, 2.x compatibility, docs/tests honesty) still found real defects:sl=0opened an unprotected position and reportedOk;ticket=0reachedpositions_get(possibly "no filter" → close everything);positions(symbol, ticket=)ignored the symbol;last_error()race could label a lost order "never sent";Fixed in 55be3e2, eeaee6b, 56457bc and 4546b05.
Eight more
/code-review highrounds on those fixes followed (23f78ff … 880ca9c). a0f2aba introduced a regression: an invariant onSymbolSpecmade positions on symbols with broken data impossible to close. Round 6 caught it, and 098ac0a reverted it before any push. Each fix commit lists its RED evidence.Verification (local)
python -m buildandtwine check --strictare clean.Needs demo-account verification (
pytest -m integration)positions_get/orders_getreturningNonevs().Known residual risks (conscious debt)
OUTCOME_UNKNOWN: safe but noisy.Broker:if broker.Buy(...)stays truthy for a partial or queued fill, as in 2.x. MIGRATION says to checkretcode.(attempts-1) × delayper position beforeNO_PRICE.NO_PRICE, even for a close that needs only the other side. This fails safe.close_positions()/cancel_pending_orders()without arguments act on the whole account (documented in bold). Decision to confirm: should they default to the trader's ownmagic?pointis unusable but whose tick size is valid, a points stop is only refused after the tick fetch. A symbol without quotes therefore reportsNO_PRICEfirst.digitscoarser than the tick size (digits=1, tick 0.25) rounds levels off the grid. The server rejects them (10015/10016) instead of us.price_on_gridandvalidate_volumefor direct callers: duplicated work, one rule.BuyLimit/SellLimitcompare the raw level with the quote, as 2.x did. A level that snaps onto the quote is placed as a limit, not filled at market.Semgrep findings
github-actions-mutable-action-taginpython-publish.yml, fixed in 16cc80b.Not done here